SPACE 2/SPACE - Library 2 - Volume 1.iso/apps/471/applic/diary_19.doc

Text File | 1990-05-18 | 53KB | 992 lines

DIARY & EdHak Versions 1.9                                 05/14/90
==========================

This documentation is for both Diary and EdHak, and any references to DIARY
also apply to EdHak.  The reason for having these two versions is so that
anyone who JUST wants an editor to safely edit files can have it, while
those of us who want the ability to edit ANYTHING can have that.  EdHak is
exactly the same as Diary, but has the two added features of (1) being able
to edit disk sectors (with which you could ruin your hard drive or floppies
by changing the boot sector, FAT, or directory), and (2) being able to edit
your ST's memory (which can merely cause bombs on your screen).

To Registered users receiving this on a disk in the mail:  The 'R' on the
end of the 1.9R means this version is for you.  It is not to be made
available for download anywhere, and I would appreciate it if you want to
share Diary with anyone, that you give them the standard DIARY_19.ACC,
(or EDHAK_19.ACC) also included on the Diary disk.  Your v 1.9R has been
personalized for you (take a look at the Help screen).  Also, it (a) is
able to save a New Configuration to disk, and it (b) defaults to
non-display of the 'cr' at the end of lines and allows you to toggle that
display on and off with Control-Return.  Please DO distribute the shareware
version of Diary to friends, BBS's etc, but please also include this
documentation file.

I think Diary has become a fairly mature piece of software, as well as
including some unique features.  Therefore, I have set the registration fee
to $10 for anyone who has not previously registered.  See the information
below in the Registration section on how to own your copy of Diary and what
exactly you get for registering.


Contents
========
New for Version 1.9
Intro for Those New to Diary
Cursor Controls
Command Descriptions (menus & keyboard commands)
Compatibility? (problems you may run into)
The Future of Diary
Registration (if you wish to own Diary after trying it out)
Final Words (disclaimer & where to reach me)


New for Version 1.9     (5/9/90)
===================

1)  Run as either .PRG or .ACC just by renaming file.  Beware that when run
as a PRG, you must remember to save your work to disk before you exit or it
WILL be lost.  This differs from running as an ACC when your work is still
there next time you open up the accessory (unless of course you have
rebooted).  Also note that you will get two bombs every time you exit from
running as a prg.  As far as I have found, this does not result in any
problem -- there is no crash or lockup of any kind.  But, since it can be
frightening until you get used to it, I've included the little reminder
alert box telling you not to care about the bombs.

2)  Now allows macro F10 to be used as a printer setup string that is sent
prior to every print operation.

3)  Control-Arrow = Move cursor to next/previous word.  The function that
this key combination used to serve, which was moving the cursor to the
start or end of the portion of a long line within the current window, is
now done with Shift-Control-Arrow.

4)  Added overwrite/append default to configuration options.

5)  Added Save with BAKup to configuration options.

6)  Window size (full/half) is now saved in config file with other current
settings.

7)  Add Alt-Z (menu2-Zap) command to send block or whole buffer to serial
port (for modem or serial printer).

8)  Much faster search routine (now in machine code).

9)  Filename is now displayed at top of window. (In low res the last couple
characters will not show if it's a full 12-character filename.)  This is
only the filename and does not include the full path.  That information can
still be found in the configuration display (Alt-N).

9a) For EdHak, when editing disk sectors or RAM, the title shows either
the starting sector of the block you loaded or the address of the block
of RAM that you are viewing.

10) I THINK everything should now be compatible with large screens
(Moniterm) and large screen emulators (MonSTEr).  Let me know if not.

11) Search routine now places the found position on the second line rather
than the top line to make it easier to see the context.

12) Merge file now defaults to a filename of 'BLOCK.TXT' so as to be the
same as the default filename for Block Save.  This makes it a little easier
to cut/paste between documents or between 2 windows of Diary.


Bugs Fixed in Version 1.9
-------------------------

1)  Properly shows "Macro Set" or "Truncated" notice when saving a macro
(CTL-FuncKey).

2)  Fixed disappearing mouse when you have two Diary windows open and do a
Search or New config. (This took a week to unravel all the interplay
between all the GEM events when multiple accessories are running.)

3)  Got rid of "Working" notice remaining after doing a global replace.

4)  Fixed bug that gave an Alert box saying "buffer full" when trying to
trying to insert something with the buffer set to 64K.  (It worked fine if
the buffer was set to 63K or less.)  Other related 64K bugs also fixed.

5)  Fixed disappearing mouse if the AutoLoad function failed to find the
desired file.

6)  Properly sets slider after encryption.

7)  Fixed bug that gave you a zero buffer size if you saved a new config
without setting a different buffer size.

8)  Fix bug that allowed cursor positioning anywhere on first line even
though the buffer was empty when in Hack mode.

9)  Hitting F6 (Find next match) before setting a string to find no longer
crashes the system.

10) Diary once again works with UniTerm, as it did before version 1.8.
Please see the Compatibility section for more details.

11) Fixed wrap column for when you save your configuration while in Hack
mode.  It used to default to 75 instead of the 64 or 32 appropriate
for Hack mode.


INTRO FOR THOSE NEW TO DIARY
============================
You can always hit the Help key or use the drop-down menu if you don't
know what you're doing.

This program is simply a text editor accessory that opens up a half-screen
window which you can move up or down on your screen, and toggle between
full and half size.  Being a desk accessory, it is available from within
any other GEM program that has a menu bar, so you can get to it whenever
you want to jot something down or view or make changes in a file without
going to get your favorite word processor or disk sector editor.  Unless
you register and get the version that allows saving a new configuration,
the text buffer is limited to 10K of data, which it allocates all at
once when you boot up.  Any text in the buffer stays there until you Clear
it or reboot, regardless of whether you have the Diary window open.
In Text mode, Diary deals strictly in text with the standard CR/LF at the
end of each line, but in 'Hack' mode it can handle anything.  It only
displays the 'cr' but the line feed is still there.  If you are editing
something other than text, just turn off the word-wrap before doing
anything else or switch to Hack mode.

If you cover up the Diary window by clicking on a desktop or application
window, you can get back to Diary either by clicking on any visible part
of the Diary window (if any is still showing) or by going to the desktop
desk accessory menu and clicking on Diary as if you were opening it.  In
most cases, it is OK to open or close an application when the Diary window
is open.  It just causes the window to close, and you can then re-open it
as usual.

One slightly strange thing in Diary is the simple little drop down menu
within the Diary window.  The items don't highlight as in a normal menu
(since I couldn't justify the added program size and programming hassle to
accomplish this), but the menu goes away just by moving the mouse outside
the menu without having to click again.

If you have less available RAM than needed for the normal versions of
Diary, but still want some way to do simple text editing, a stripped
version of Diary called DIARY19S.ACC is available that only takes up 43K of
ram (compared to about 74K for the full version 1.9).  This was
accomplished by decreasing the buffer size to 4K and removing a number of
features, most notably the word wrap, all block functions, and all menu2
functions.


CURSOR CONTROLS
===============
Arrow keys               =  Left, Right, Up, Down
Shift-Up/Down arrow      =  Page up/down
Shift-Left/Right arrow   =  Go to start/end of line
Cntrl-Left/Right arrow   =  Go left/right to previous/next word
Shft-Cntrl-Left/Rt arrow =  Go to left/right edge of line in window
                              (useful for lines longer than window)
ClrHome         =  Toggle cursor to top/bottom of screen
Shift-ClrHome   =  Toggle cursor to top/bottom of buffer
Tab             =  Go to next tabstop (inserts spaces if in insert mode)


COMMAND DESCRIPTIONS  (in menu sequence)
====================

Menu 1 and Menu 2
-----------------
The 'Menu' button near the left end of the window title bar gives access to
all the file, editing, and configuration commands.  When you first move
the mouse into that area, then the first menu, Menu 1, drops down.  If you
then click the left mouse button in the block that now says: 'To Menu 2',
you will cause Menu 1 to be replaced by Menu 2, which has commands that are
less likely to be needed as often.  The drop down menu goes away just by
moving the mouse outside the menu area, with no clicking needed.

Note that in my attempts to minimize the size of the program, I have not
added the code to make the menu items highlight as the mouse moves over
them.  So, just point to the command you want and click the left mouse
button to make it happen.


Open File  (Alt-O, Alt-R, menu: Open...)
---------
This lets you read a file of ANY type (text, doc, prg, tos, rsc, etc.)
or (with EdHak only) any range of disk sectors into the edit buffer.  If
the file is anything other than ASCII text, you will see funny characters
on the screen for each non-ascii byte.

If the file is larger than the buffer, you will be asked what portion of
the file to load.  You can use the keyboard or mouse to set which part of
the file to load -- zero loads the first part of the file, '1' loads the
file starting at a point 1K (1024 bytes) into it, '2' starts 2K into it,
etc.  The amount of the file that gets loaded is 2K less than the buffer
size.  So, with the default 10K buffer, it will load in 8K.

If you already have stuff in the edit buffer that hasn't been saved, you
will be asked if you want to save it first.  After taking care of that,
you will be asked if you want to open a New file or Merge a file into the
current one at the cursor.  Opening a new file will destroy everything
currently in the buffer.

If you choose to merge a file into the current one and there is not enough
room in the buffer, the merge will not be done at all -- there is no
provision to merge just part of a file.  You can always get around that by
first saving the current file, loading the one you wanted to merge, saving
a block from that one, loading the original file, and then merging the
block that you had saved.

If you leave the filename portion of the file selector blank, and you have
the disk editing option enabled (as it is in EdHak), then the disk drive
you have chosen is opened as if it were simply a huge file, and you get to
choose which block of sectors to load into the edit buffer.

For useful information on opening and editing files other than ASCII text
files (including disk sectors), please see the Hack Options section below.


Save File  (Alt-S, menu: Save...)
---------
This always gives you a file selector to choose the filename you wish to
have the file saved as.  It will default to the filename you last opened if
there was one.  If you try to save to a filename that already exists on the
disk, it will warn you of this and ask if you want to Overwrite the old
file, or Append to the end of that file.  The Append option is handy if you
are using it as an actual diary, or if you want to add text to the end
of a large file without having to read that file into the buffer first.
Note that this initially defaults to Overwrite (without a backup), but then
defaults to whichever you last used.  Also, using the configuration options
described below, you can force it to initially default to Append and/or
always save with a backup if you wish.

If you have a block selected, you will be asked if you want to save just
that block or the entire buffer.  It defaults to saving only the block.


Opening/Saving Files larger than the Diary buffer or
even larger than your ST's total memory!
(or when is 10K equal to 100 megs?)
-----------------------------------
Despite Diary's small (default of 10K) text buffer size, it will handle ANY
size file by loading in only a portion of the file that you want.  It is
"limited" to the first 99 megabytes, just because the biggest number the
dialog box lets you enter is 99999.  If anyone finds this to be a
limitation, let me know!  Block zero is the first 8K block of the file, and
the dialog box will allow you to go up to a block starting at about 1K from
the end of the file, which would give you over 8K of free space to add text
to the end of the file.  When you go to save the file, Diary will take care
of stringing together the text from the original file with the block of it
that you edited to create a new file.  This means that it won't overwrite
the latest version of the original on disk, since it needs that to create
the new version to be saved.  For you power users this also means that you
should be careful if you have two copies of Diary or Diary plus another
editor running at the same time, not to make changes in the same document
on disk or in both windows of Diary, and then expect to be able to save a
complete file from both.

Since you can only load an 8K block of a file that is bigger than 10K, it
will require more work to do some things, like doing a cut/paste from the
end of a big file to its beginning.  To do such a thing you would need to
first save the file after the Cut, then read in the other portion of the
file, and finally do the Paste.  Or to handle a block larger than the
paste buffer size, you can first save the block to disk and then use the
Merge feature to paste it at the desired location.


On-line Help  (Alt-H, HELP key, menu: Help!)
------------
This displays a brief list of the commands and what they do.  This includes
cursor controls, file handling, configuration, and all editing commands.
Note that the README file will include any new commands that may not have
made their way into the help screens.


Word Wrap  (Alt-W, F10, menu: Wrap...)
---------
This command first gives you an alert box with the choices of Wrap!...,
Cancel, or Turn Off.  With Wrap turned On (which is the default), Diary
will word wrap to a default line length of 75 characters, plus the CR/LF
for a total of 76 (or 64 if in 'Hack' mode, or appropriately shorter
lengths in low resolution).  This length can be changed with the Alt- '>'
command.  Word wrap occurs automatically when adding to the end of your
text and you hit the word wrap column, or when inserting text in a line
that reaches the wrap column.  With Wrap turned Off, you can create/edit
lines of any length (within the size limit of the whole buffer, of course).
Turning Wrap off also can be useful if you get annoyed by the constant
redrawing of the the rest of the screen while inserting text.  In this
case, all the text you insert will be on one line until you force it to
wrap using the Wrap! command.  Regardless of whether Wrap is turned on or
off, you can always force a wrap (reformat a paragraph, line, or whole
buffer) with the Wrap! button of the alert box.  I have gotten very quick
at hitting F10, Return, Return to reformat the current paragraph.  Diary
assumes paragraphs are separated by a blank line.

To change the column at which word wrap occurs, please see the description
of the Margins command below ( Alt- > ).


Print  (Alt-P, menu: Print...)
-----
This allows either printing the whole buffer or just a marked block.  If
your printer is not already turned on, or if it is not properly connected
to your computer, an Alert box will instantly tell you that your printer
is not responding.  For more information on selecting a block, please see
the Select Block section below.  If a block is already selected when you
give the Print command, it will default to printing just that block unless
you click on the 'All' button in the alert blox.

Note that you can send any printer control codes you want to set left
margin, bold, near letter quality, or any other things your printer can do.
All you have to do is look at your printer manual to find out what codes
do what.  For example, on my printer (which is pretty much Epson
compatible) the code to set the perforation skip is Esc-'N'-'x', where x is
the number of lines to skip.  To get the escape character, type Control-[
(or Alt-Esc), then type upper case N.  Then type Control-I to set a
perforation skip of 9, since I is the ninth letter of the alphabet (don't
worry about the funny character that appears - that's just what the ST uses
for displaying this control code which is normally non-printable).

If you have one or more printer control strings that you want to be
able to send to the printer without typing them in each time, this can be
done using macro.  Please see the sections on Macros and Configuration
below for details on this.

If you need to print out of the serial (modem) port, please see the Zap to
Modem section below.


Clear Buffer  (Alt-C, menu: Clear buffer)
------------
This command wipes out everything currently in the edit buffer, but it will
always ask for confirmation before doing it.


Block Cut/Paste and all Delete functions
(Alt-B, F1-F5, Delete, Shift-Delete, UNDO)
==========================================

Select Block  (F1 & F2 or mouse)
------------
A block can be selected either by using the mouse or using F1 and F2.
To use the mouse, hold down the left button while dragging the mouse
either up or down to the end of the desired block.  If you drag to the top
or bottom of the window, the text will scroll while continuing to select
the block, so it is easy to select blocks larger than the size of the
window.  If you use the function keys, F1 sets the start of a new block
(thus cancelling any prior block selection).  F2 sets the end of a block,
which can be either before or after the start.  Note that if you hit F2
again after moving the cursor outside the existing block, it will extend
the block to that new point, but if the cursor is within an existing block,
F2 will shrink the block.  Also note that the last character of a block is
always the character preceding the cursor -- this makes it easy to select
an entire line without also including the first character of the next line.

Deselect Block  (F3 or mouse)
--------------
To deselect a block either hit F3 or use the mouse to set the end of a
block at its starting point.


Cut Block  (F4, Alt-B, menu: Block...)
---------
This command deletes a block that you have already selected and places it
into a paste buffer.  Each time you use this command you lose anything that
was already in the paste buffer.  If you just want to make a copy of a
block rather than deleting it, first Cut it, then hit UNDO or F5 (which
pastes it), and finally put the cursor where you want the copy to go and
paste it again.  The paste buffer will remain intact until you do any
further deletion of any type or until you cause a word wrap to occur.  If
you try to cut a block larger than the paste buffer can hold, you will be
asked if you wish to Continue without any Undo or Paste capability (thus
losing the block forever) or Cancel.

If you wish to save a block to its own disk file, select a block and then
use one of the Save File commands described above.

Paste Block  (F5, UNDO, Alt-B, menu: Block...)
-----------
This inserts the contents of the paste buffer at the cursor.  You may then
need to reformat using the word wrap command.


Delete Character or Line  (Delete, Shift-Delete)
------------------------
Deleting a line (or multiple lines or characters in sequence) has the same
effect as doing a block cut of them.  So, to delete or move a few entire
lines, it may be easier to just hit Shift-Delete a few times rather than
marking them as a block and cutting them.  As long as you don't move the
cursor between deletions (and don't force a word wrap), each new line or
character will just be appended to the paste buffer without losing its
previous contents.  However, please note that hitting Backspace DOES empty
the paste buffer of everything except the character you just backspaced
over.


Technical Notes  (paste buffer, line pointers, and word wrap)
---------------
The paste buffer, which is used to hold cut blocks and deleted lines and
characters, is not very large.  It is equal to 1/8 the size of the edit
buffer (1280 bytes in the case of the normal 10K buffer).  This buffer is
also used for word wrap operations, so anything in the paste buffer is
lost as soon as any word wrap is done.  This buffer is the same size as the
block of memory that is used to store pointers to the start of each line.
Since each pointer is two bytes long, the default 10K edit buffer can
handle up to 1280/2 = 640 lines.  If you load a file with lots of blank or
short lines, you could exceed that, in which case the file will load, but
the last line will just be one long line containing all the rest of the
file.


Search/Replace  (Alt-F, menu: Find/replace, F6)
--------------
When you choose this command, you are first asked if you want to just Find
something or perform a Search & Replace operation.  This defaults to Find.
Next you enter the string to search for.  Normally, this would be entered
as a string of characters, including any control characters such as
Cntrl-M/Cntrl-J for carriage return/linefeed or Cntrl-I for the tab
character, etc.  Alternatively, you can enter any of the full 0-255
character set by using their two-digit hexadecimal values and putting a
dollar sign ($) at the start of the string.  For instance, to enter
CHR(155), you would type '$9B' without the quotes.  The null character
would be '$00'.  If you are a masochist, you could also use hex values to
enter normal text -- the hex string for 'XYZ' would be '$585960'.  The
letters A-F in hex strings can be entered in either upper or lower case.

One little thing to be aware of is that any underline character at the end
of the string will not be recognized as part of the string.  This is
because GEM uses the underline character in the dialog box as the
background template, and I find the end of the string by searching backward
until I find the first character that is not an underline character.

After entering the search string, you are asked whether to make the search
case sensitive or not.  This initially default to No, which means that it
will match either upper or lower case versions of the search string.
Anytime you change the case sensitivity of the search, that becomes the new
default.

If you have chosen Replace, then you get to enter the replacement string.
Then you pick whether to Query (i.e., ask you what to do when it finds each
match) or just go ahead and replace every match it finds without asking.
The default is always Query.  If you pick Query, then each time it finds a
match you get to tell it whether to (a) skip to the Next match without
replacing this one, (b) Replace this match, or (c) Quit searching.

Once a search string has been entered, you can always just hit F6 to find
the next match.

As a final note, if you need really fancy search/replace capabilities, I
can recommend another program of mine called SRCHREP.PRG, which allows
various types of wildcards in search strings (alpha, decimal, hex
wildcards) and replace strings (leave unchanged, make lower case, and make
upper case wildcards), as well as replacing only every Nth match when doing
a global replace.


Quit  (Alt-Q, Alt-X, Esc, menu:Quit, mouse:CloseButton)
----
You wouldn't think Quitting would require any explanation, would you?
But there are a few things to know.  If you use Alt-Q, Esc or menu:Quit,
then you will always be asked if you want to save your work if any changes
have been made since the last time it was saved.  If no changes have been
made, it will just ask if you Really want to quit.

If you use either Alt-X or clicking on the window's close button (upper
left corner), then Diary will just plain quit regardless of whether you've
saved your changes or not.  If you are running as a desk accessory, failing
to save changes is not too terrible, since you can just re-open Diary and
everything will still be there (until you reboot).  But beware that if you
are running it as a PRG, then you better be sure anything you care about
has been saved to disk, because everything in the buffer is lost as soon as
you quit.


Margins  (Alt- <, Alt- >, menu:Margins)
-------
No, you don't have to hold down the shift key for the Alt- < and Alt- >
commands to work -- I could have said Alt-comma and Alt-period, but I
figured the < and > symbols made more sense for left and right margins.
Please note that the left 'margin' refers only to what gets sent to the
printer and has no effect on what displays on the screen.  This works
by sending space characters to the printer at the start of each line,
so it should work fine with any type of printer.

The right 'margin' is not really a margin, but is the column at which word
wrapping occurs, and it does affect the screen display.  Both left margin
and right wrap column are measured from the furthest left column which is
column zero.  Thus the default right wrap column for medium and high
resolution is 75, which gives 76 columns including the end of line
(carriage return) character.  The right wrap column can be set to any value
greater than 19 on up to infinity (well, maybe not quite infinity).
For other information on word wrap, please see the Word Wrap section above.


Note on extended lines  (longer than one window width)
----------------------
Be sure to turn off Wrap before trying to edit a line that extends beyond
the first window, unless you want it to wrap when you hit the end of the
second (or later) window.  Simply moving the cursor with the arrow keys
beyond the furthest left or right columns of the window will move you to
the next or previous section of the line.  Shift-left or right arrow takes
you to the start/end of the line, no matter how far over it is.  Another
command, Control-arrow, takes you just to the left or right edge of the
current window.  Clicking with the mouse by the edge of the window will
also take you to the next/previous section of the line.

One interesting thing you can now do with wrap turned off is to use Diary
instead of a sector editor to Find and then change text strings in PRG,
TOS, or any other file.  Just be careful not to change the length of them!
Toggling into Hack mode automatically turns Wrap off.


Tabs  (Tab, Alt-Tab, menu:Tab settings)
----
In insert mode, the Tab key inserts whatever number of spaces you have it
set for (default is 5).  In overwrite mode, it skips over that number of
spaces rather than erasing anything.  I figured it would be more useful
that way for editing existing tables.

To change the spacing between tab stops, use either the Alt-Tab command or
the menu:Tab settings command.  All tabs have the same spacing between
them.


Macros  (Control-FunctionKey, Alt-FunctionKey, menu:Macros)
------
This refers only to text macros -- there are no command macros.  In other
words a macro is simply a string of characters that you can insert
whenever you want without having to type them all in.  This might be
useful for entering your name and address at the top of letters or keeping
various printer set-up strings handy for different types of printing needs.
There are 10 macros available (one for each function key), and each can
hold up to 80 characters.

To store a string of text as a macro, first select a block as described
above under Select Block, then copy the block to a macro with Cntl-FuncKey.
For instance, to set up the macro for F1, select a block and then hit
Control-F1.  Then when you want to insert that macro, hit Alt-F1.  The
menu:Macros command first reminds you how to save and then use a macro, and
then displays all ten macros, one per line.  Note that if you want the
macros to still be there after rebooting, you need to save the
configuration, which requires a registered version of Diary.


Date Insertion  (Alt-D, menu:Date insert)
--------------
This command inserts the current date at the cursor using the format
MM/DD/YY, as in 05/03/90 for May 3, 1990.  This assumes you have your ST's
date set.


Configuration  (Alt-N, menu:New config?, Control-Return)
-------------
This provides user-alterable buffer size (4-64K) and many other options.
(Saving a new config file and new buffer size is available only to
registered users.)  This command first shows your current status and
settings:  file name, path, buffer size/used, margins, end of line
character, insert/overwrite mode, tabs, case sensitivity in search, wrap
on/off mode, tabs, text/hack mode, whether macro 10 is sent as a printer
init string, and the ten macros (display of the macros is truncated to what
will fit on one line).  To toggle the End-Of-Line character between blank
and the little 'cr', hit Control-Return anytime you are in edit mode (not
while looking at the configuration display).  Not shown in the config
display, but viewable by trying to Save to an existing disk file, is
whether the Save command defaults to Overwrite or Append.  Its current
default gets saved to the config file along with all the other
configuration settings.

You are then given the option of changing the buffer size, but this does
not take effect until you reboot (or reload into Multi-Desk).  Note that
if you start dealing with a buffer contents larger than about 20K, you will
start to notice a slowdown when inserting or deleting near the beginning of
the buffer.  This happens despite the fact that I use what is probably the
fastest machine code routine possible to move everything around in memory.
For more info, read the tech notes below.

Next, you get to set whether or not to AutoLoad the current file on bootup.
This is of use only to registered users, since it requires saving a new
configuration.  This option allows you to specify a file for Diary to load
into its buffer automatically upon bootup, so when you open Diary the file
is already there without you having to go find and open it.  This is
especially useful if you are always editing the same file such as a diary.
You set this up by:  (a) load the file of interest into the buffer, then
(b) go to New Config (Alt-N), and (c) click through the screens until you
are asked if you want to AutoLoad the current file, and finally (d) click
on Yes.  The full path and filename get saved to the DIARY.CFG file along
with the rest of the current configuration (assuming you tell it to really
save the configuration when it asks at the end of all the configuration
alert boxes).  If it can't find the specified file upon bootup, it just
skips over that routine and no harm is done.

Next, you are asked whether to use macro #10 (Alt-F10) as a printer
initialization string which will be sent to the printer before every print
command.  This can be used if you always wish to tell your printer to do
something like perforation skips or print in NLQ mode or any combination of
printer commands up to 80 characters long.  See the section on Printing
above for more info.  If you have more than one printer setup string that
you'd like always available, you can save the others as macros too and then
just insert the one you want at the beginning of the file or block before
printing it.

The last config option you get is whether to keep a backup (.BAK) file
whenever saving with Overwrite.  When saving with BAKup, Diary first
deletes the previous .BAK file (if there is one), then renames the current
disk file with a .BAK extender, and finally saves the new version of the
file to disk.  Therefore, if any error occurs in saving the new version,
the prior version will be there with the .BAK extender.

Finally, you are asked if you want to save that whole configuration.  Even
if you don't save it to disk, the changes you made (other than buffer size)
will still be in effect until you reboot.  Note that everything except the
buffer size gets saved to a DIARY.CFG (or EDHAK.CFG) file, while the buffer
size gets written into the main DIARY19R.ACC file itself.  For the config
to be read upon bootup by Diary, this CFG file must be in the same folder
or root directory as the main Diary file itself.

NOTE:  The file must be named its original name (e.g., DIARY19R.ACC, or
EDHAK19R.ACC) for it to be found for writing the new buffer size.  However,
I realize you may have reasons to name it something else, such as if you
want to have two copies of it loaded at the same time, or different copies
with different buffer sizes.  To do this, just rename it AFTER you have
saved the desired buffer size to it.

**************************************************************************
Tech Notes on Memory Management & Buffer Size in Diary
------------------------------------------------------
The buffer size must be saved to the main acc file as part of the BSS
length in the file header (rather than reading it in from a separate config
file) to be able to safely allocate the proper amount of memory.  Other
desk accessories that use a more typical method of allocating memory
(dynamic allocation using a Malloc call) are not handled properly by TOS
and will steal gobs of extra ram if you ever try switching between low and
medium resolutions, because TOS does not deallocate that ram before
allocating it again.

Diary handles the text buffer is simply one continuous block of RAM, and so
to insert or delete near the beginning of that can require moving around
a large chunk of ram.  I use a very fast machine code routine to do this,
but it obviously isn't fast enough when you get above about 25K.  The way
other word processors get around this is to dynamically allocate small
chunks of ram as needed and link them together with pointers thus requiring
much fewer actual bytes to be moved.  That approach takes more ram to
handle the same amount of text, and more importantly, if that approach is
used in an ACC things get screwed up in a low<->med resolution switch,
which is why I gave up on it months ago.  However, when I get more into the
prg version of Diary, I hope to work on it some more.  Incidentally, the
slowdown is exactly the same thing you run into with Flash's buffer, if you
ever use that.
**************************************************************************

Encryption  (Alt-E, menu:Encryption)
----------
This command lets you make anything in your buffer confidential by
encrypting it using a password of your choice.  You MUST remember your
password to be able to unencrypt it, which is done using the same command.
You can even encrypt it more than once using different passwords, and then
unencrypt it using the same passwords in any sequence you like.  One major
caution on encryption:  If you password is more than one character long
(which is certainly a good idea), then do NOT use the Append, Merge, Block
Save features or load/save a file larger than your buffer because the
decryption will not work properly unless you get very lucky (e.g., the file
length is an exact multiple of the password length.)


Hack Options (Alt-T, Alt-V, menu:Hack Options)
------------
1)  Toggle Text/Hack mode (Alt-T)
For most word processing needs you will want to use Text mode, which
starts a new display line for every CR/LF [ CHR(13), CHR(10) ] combination
in the file (or any time you hit Return while entering text from the
keyboard).  Text mode displays every character, 0-255, EXCEPT the CR/LF
combination, which it either displays as the little 'cr' symbol or as a
blank (null) space at the end of each line.  The blank option is only
available to registered users.  Also, while in Text mode, the current
Line and Column of the cursor are shown in the top window bar, measured
from line zero at the top, and column zero at the left edge.

Hack mode displays all 0-255 characters including the CR/LF combination as
individual characters.  In Hack mode, CR and LF are treated just like any
other characters, and every line is displayed with a length of 64 (or 32 in
low res) unless you change the right wrap column while in Hack mode.  This
is similar to the displays found in disk sector editors, except that you
can't display the whole window as hexidecimal.  However, the hex value of
the character at the cursor is shown in the top window bar, preceded by
a '$' sign.  I figured that if you need to look for a string of hex values,
it makes more sense to let the Find command do it for you than to try to
visually find them on the screen.  Also shown to the left of the hex value
is 'n' which is the number of bytes (characters) you are from the top of
the buffer -- this could also be called the offset.  The first character is
therefore number zero.

2)  View/Edit RAM  (Alt-V)
Yes, you can load any part of your ST's memory into the edit buffer, either
by searching for a sequence of characters or by choosing which specific
block of memory to load.  Then you can edit it, save it to a file, or even
write it back RAM in its original or some other location.  Hack away!  but
don't complain to me if your machine crashes after you change something in
RAM.  The RAM you can access includes addresses from zero up to whatever
your operating system thinks is the top of physical RAM (phystop).  This
includes all the system variables, screen ram, etc.  However, with the
ramdisk I use (Eternal2), phystop is lowered to fit the ramdisk above it,
so phystop becomes lower than the actual top of physical ram.  To get to
that RAM in a ramdisk you can use the disk editing feature described below.

3)  You can use the EdHak version of Diary as a disk sector editor!  To do
this, start as if you were going to open a file, but leave the filename
part of the item selector empty and just specify which drive you want.
Then open it and you will be asked which sector to start reading from.
Sector zero is the boot sector, and this is followed by two copies of the
FAT (file allocation table), then the root directory, and finally the
actual file data.  Unless you are using a very strange format for your
drive (i.e., something not supported by GEM), files are stored in 1K chunks
called 'clusters' each of which consists of two 512-byte 'sectors'.  Diary
will load as many sectors as will fit into the buffer and still leave you a
couple K to add to it, just as if you had loaded part of a file that was
too big for the buffer.  If you don't know anything about disk structure,
do NOT try saving this back directly to disk sectors.  If you want to save
it as a file, then give it a filename and all will be safe.  If you DO know
what you are doing, then this disk editing feature provides some different
options from anything you are likely to find in a typical disk/sector
editor, since you can view/edit more than one sector at a time, toggle into
text mode, insert, append to files, etc.  I understand that there is a
program available called something like MIRROR that lets you save the FAT
and root directory to a disk file and then restore them if they ever get
corrupted.  Well, now you can do the same thing with EdHak alone.


Insert Hex or Text String  (Alt-I, menu:Insert bytes)
-------------------------
This is for direct entry of all 256 characters (0 - 255).  To enter ones
above ASCII #127 you need to enter their hex values (unless you know some
key combination that I don't that will do it!).  For instance, to get the
trademark symbol (little 'TM') on the screen, you need ASCII #191
(decimal), which is also known as CHR(191), which is $BF in hex.  Don't
expect your printer to output a 'TM' though.  On my printer, character #191
is an italics question mark.

Note that here and anywhere a string is to be entered, such as for
search/replace, entering hex byte values gives access to all 0-255 possible
characters.  Hex digits must be entered starting with a '$' and then must
be entered in pairs or the string will be interpreted simply as a string of
characters rather than hex values.

One special character has its own keyboard command.  The Escape character
CHR(27) can now be output with Alt-Esc as well as the normal Control-[
(which puts out ASCII character #27, just like Control-A puts out ASCII #1
and Control-Z puts out ASCII #26).  This can be useful for putting in
printer control codes -- see section on Printing above.


Zap to Modem / Serial Port  (Alt-Z, menu: Zap to modem)
--------------------------
This command prints the buffer or just a marked block to directly out the
serial RS232 port, just as if you had Printed it to the printer.  This
command can be useful when telecommunicating when you want to send a few
lines of text from some existing file without loading it into your terminal
program's buffer.   Note that since it treats the output as if it were
going to a printer, it first sends the printer setup string (macro #10) if
you have the configuration set up to do that, and then sends spaces at the
start of each line, if you have a left print margin set to anything higher
than zero.  So you may need to change your configuration before using this
command -- but you don't need to reboot to make the new configuration
active.

The only difference between printing out the modem (serial) port and
printing out the printer (parallel) port is that no carriage return,
CHR(13), is sent at the end of the whole print operation when Zapping to
modem, but one is sent when printing to the printer port, since printers
usually need this to clear the last line from their internal buffer.  So,
if you are printing to a serial printer rather than to a modem, you need
to make sure you have a CR at the end of the last line of your text.


Compatibility?
=============
Pinhead
-------
I use the Pinhead fast-load AUTO folder program all the time when booting
from my hard drive, and I have never seen a problem with it.  However, when
I went to the Toronto Atari show without a hard drive I stayed up til 3:00
AM tracking down why Diary wouldn't work, and the solution was to get rid
of Pinhead.  So if you want to use Pinhead, you may have to disable it for
loading of Diary.  Refer to the documentation that comes with Pinhead on
how to set up a data file telling Pinhead not to fast-load Diary.

Quick ST and Turbo ST
---------------------
Use of either of these screen output speedup programs is highly
recommended.  Diary versions 1.8 and later incorporate a fast machine code
routine that outputs text directly to the screen without using the built in
GEM BIOS functions or even slower VDI functions.  This bypasses any speedup
for text output provided by Quick ST or Turbo ST, BUT they still greatly
speed up the screen clearing and scrolling functions, so they are well
worth using if you have enough RAM for one of them.

Diary has always been compatible with Turbo ST (at least through Turbo ST
version 1.6 which is the latest I have).  However, with Quick ST there are
a couple problems you may have run into in earlier versions that are now
fixed.  Version 1.8 and later of Diary should be compatible with any
version of Quick ST, and starting with version 2.0 of Quick ST, it seems
compatible with any version of Diary.  Earlier versions of Quick ST had a
little bug when run with TOS 1.0, which caused the cursor to do strange
things with earlier versions of Diary.  Starting with Diary v 1.8 I simply
bypassed all the cursor drawing routines so Quick ST couldn't mess them up.
Then in version 2.0 of Quick ST Darek Mihocka fixed the bug.

Flash
-----
Compatibility with Flash is now almost perfect:  Opening up Diary now
almost always draws the window fully (and when it doesn't it's no big deal
since just resizing the window fixes it).  And if you go to Flash's on-line
mode without exiting Diary, you can now return to Diary without crashing
(after getting back to Flash's edit window, of course).  That one took a
couple entire weekends of work to figure out, and I caution you not to try
that with any other text editor accessories or any accessory that opens a
window (such as the Atari control panel).  Finally, the cursor position
does not now get screwed up when going back and forth between Diary and
on-line mode.

One little weirdness still exists with Flash when running Diary from within
Multi-Desk version 1.8 (I don't know about later versions).  If you have
done the sequence described above (going to on-line mode without closing up
Diary yourself), then as long as you remain in Flash anytime you click on
Multi-Desk you automatically open Diary without getting to choose anything
else that might be in the Multi-Desk menu.  Then this menu also gets
bypassed when quitting from Diary.

UniTerm
-------
Version 1.8 of Diary became incompatible with UniTerm because of the fast
screen output I started using, but this has now been fixed in Diary v 1.9.
To output text directly to the screen I needed to know where in RAM the
screen was located, and I got that location during the initialization at
bootup.  However, UniTerm changes the screen location for its help screen,
which is where you get access to the desk accessories.  So, I fixed Diary
to get the screen address each time its window gets opened, so it knows
where to draw the text.  This probably fixes problems with some other
programs too.

Please note that in UniTerm, unlike Flash, you MUST exit Diary before
switching to on-line mode, or else UniTerm will lock up as soon as you try
switching back to Help mode or try exiting from UniTerm.

Others?
-------
Please let me know of any other compatibility problems you run into so I
can try fixing them or at least document them to save others as much
hassle as possible.


REGISTRATION
============
This program is shareware, not freeware.  This means that you get to try it
out for free.  If you find that you want to keep using it, then you are
supposed to pay for it so you can legally own it.  I have been considering
distributing this commercially, but that would require much fancier (more
expensive) packaging and printed documentation, as well as giving the
distributor 60% of the retail price.  The end result of would be to force
the price up to at least $15 or $20 just for me to keep from losing money.
Personally, I much prefer the idea of making software available to as many
people as possible for as little money as possible, and letting everyone
get to really try it out before having to buy it.  THAT is what shareware
is all about.  Therefore, you are welcome to use Diary & EdHak for a month
as much as you like.  If you decide it's not for you, that's fine.  But if
you decide it's a piece of software you'd like to own, then just send me
the $10.00 registration and you will be rewarded with a more full-featured
version.

For the $10 registration I would gladly provide custom versions with
different ALT-key and function key assignments.  Registration will also
make me much more willing to answer questions and incorporate suggested
changes.  I am very interested in suggested improvements, bug reports, etc.
Further improvements are expected, even if I start putting more time into
the educational/metapsychological software project I'm working on.  If you
use Diary, but don't feel that it is worth $10 to you, send me $5 and any
suggested improvements, and I will still register you.  Registering either
Diary or EdHak gets you registered for both.

The Modula-2 source code for an early version has been uploaded to at least
the GEnie information service, and I would happily provide source for the
current version to any registered user for your own personal use.

UPGRADES
--------
Registered users can always get the latest version by sending me $3 or
more (up from $2 by popular demand) to cover my cost of disk and mailing.
I will send a post card to all registered users to let you know whenever I
come up with a major new version (next will be 2.0).  The version available
to non-registered users will always have some feature(s) disabled.  For
instance, non-registered users will always have to live with the 'cr'
character at the end of the lines, and you can not save a new
configuration.  I don't consider these major, but just a little added
incentive to register.


The Future of Diary  (no guarantees, but there is more I want to do)
===================
1)  I plan to add the ability to search large disk files (infinitely large)
and disk sectors to find which part you want to load into the buffer.  The
routines to do this would also let me change the Encryption feature to
work on a whole file of any size, rather than just what will fit into the
buffer (which has limited the encryption capability to the buffer size so
far).

2)  I need to have a 'bookmark' capability, which will probably just be a
command to find the block starting point, so the Start Block command can
also be used to set a bookmark.

3)  I will probably change the configuration procedure to a dialog box
showing all the config options rather than the current method of showing
a separate alert box for each one.

4)  When word wrapping an existing paragraph (i.e., reformatting it) if a
sentence ends with a period at the end of a line followed immediately by
the carriage return, only one space will be put after the period if it ends
up elsewhere on a line due to the wrap.  To be fully correct it would need
to put two spaces after the period, and I will have a whack at fixing that.
Also, I may make it recognize paragraphs that are separated only by an
indent (i.e. at least one space) rather than requiring a blank line
between them.

5)  Maybe create my own sliders/arrows that repeat (the GEM ones don't
without TOS 1.4).

6)  I MAY eventually see about making the drop-down menu items highlight as
you move the mouse over them.  But I consider that basically a cosmetic
improvement, and I'm not much into putting effort into cosmetics.

7)  I don't know if there's a way to do it, but I'd like to make the
desktop directory windows update themselves when a file is saved from
Diary.  For now you have to hit Escape after leaving Diary to get the
window updated.  (Just as is true with Universal Item Selector).

8)  Deal directly with files with other end-of-line characters (e.g., just
LF).  For now you have to do a full search/replace to change some other end
of line character sequence into CR/LF to use Diary in its text mode.

9)  I will look further into using a different memory handling method to
speed things up when dealing with a large buffer, and possibly allowing
sizes above 64K.

10)  I have played with running other programs from within Diary with some
success (e.g. running ARCShell to unarc some files), but so far it leaves
the screen really messed up after exiting the other program and
returning to Diary.


Final Words
===========
Standard Disclaimer:  This software and documentation have no warranty of
anything.  You use it at your own risk.  I use it myself all the time, but
since I can not possibly check it out with every hardware/software set up
out there, I can only offer to try to fix any bugs that you find and report
to me.  Of course, if you received a bad copy of it from me, I will gladly
exchange that disk for a good copy.

DIARY.ACC & EDHAK.ACC version 1.9, copyright 1990 by

Craig Harvey

GEnie:      c.harvey
CompuServe: 73047,600

Clear Thinking, BBS: 313-761-2444    P.O. Box 715  Ann Arbor, MI  48105